\section{Nombre}

\texttt{Bench::Test::Remote}

Automatiza ejecuciones en máquinas remotas

\section{Sinopsis}

\begin{verbatim}
   my $remote = Bench::Test::Remote->new(
      HOST       => 'user@some.host.com',
      WORKDIR    => '/home/user/mm',
      EXECUTABLE => 'mm',
      BASEDIR    => './base_somehost',
      OUTPUTFILE => 'output.dat',
      PREAMBLE   => sub {
         my $machine = shift;
         $machine->put(['mm.tar.gz']);
         $machine->system('tar xfz mm.tar.gz');
         $machine->chdir('mm');
         $machine->system('make');
      },
      POSTAMBLE  => sub {
         my $machine = shift;
         $machine->chdir('..');
         $machine->system('rm -rf mm');
         $machine->system('rm mm.tar.gz');
      },
   );
\end{verbatim}
\begin{verbatim}
   my $parameters = ...
   my $output = $remote->get_result($parameters);
\end{verbatim}
\begin{verbatim}
   $remote->save_result($parameters, $testname);
\end{verbatim}

\section{Descripción}

El objeto \texttt{Bench::Test::Remote} permite encapsular la
ejecución de programas en máquinas remotas. Dispone de dos
métodos que permiten obtener la salida de la ejecución o almacenarla
respectivamente: \texttt{get\_result} y \texttt{save\_result}.

El objeto \texttt{Bench::Test} hace uso del módulo \texttt{GRID::Machine}
escrito por \textbf{Casiano Rodríguez León}.

\subsection{Un ejemplo}

Supongamos un programa cuya salida sea la siguiente:

\begin{verbatim}
   user@some.host.com:~/projects/Bench-Test/examples/mm$ ./mm dat/mm_200.dat 
   Filas primera matriz: 200
   Filas segunda matriz: 200
   Columnas segunda matriz: 200
   Time of product: 0.210942
   Result: 4102
\end{verbatim}

Creamos un objeto \texttt{Bench::Test::Remote} de la siguiente forma:

\begin{verbatim}
   my $remote = Bench::Test::Remote->new(
      HOST       => 'user@some.host.com',
      WORKDIR    => '/home/user/mm',
      EXECUTABLE => 'mm',
      BASEDIR    => './base_somehost',
      OUTPUTFILE => 'output.dat',
      PREAMBLE   => sub {
         my $machine = shift;
         $machine->put(['mm.tar.gz']);
         $machine->system('tar xfz mm.tar.gz');
         $machine->chdir('mm');
         $machine->system('make');
      },
      POSTAMBLE  => sub {
         my $machine = shift;
         $machine->chdir('..');
         $machine->system('rm -rf mm');
         $machine->system('rm mm.tar.gz');
      },
   );
\end{verbatim}

Con una llamada a \texttt{get\_result} como la que sigue:

\begin{verbatim}
   my $output = $remote->get_result('dat/mm_200');
\end{verbatim}

Obtendríamos en \texttt{\$output} una salida similar. En cambio,
con una llamada a \texttt{save\_result} como esta:

\begin{verbatim}
   $remote->save_result('dat/mm_200', 'test200');
\end{verbatim}

La salida del programa sería almacenada en el fichero
\texttt{test200.base} dentro del directorio definido en la
llamada al constructor como \texttt{BASEDIR}, en la máquina local.

\section{Métodos}

\subsection{El constructor \texttt{new}}

Véase una llamada típica:

\begin{verbatim}
   my $remote = Bench::Test::Remote->new(
      HOST       => 'user@some.host.com',
      WORKDIR    => '/home/user/mm',
      EXECUTABLE => 'mm',
      BASEDIR    => './base_somehost',
      OUTPUTFILE => 'output.dat',
      PREAMBLE   => sub { ..preamble code.. },
      POSTAMBLE  => sub { ..postamble code.. },
   );
\end{verbatim}


Este método devuelve una nueva instancia de un objeto
de la clase \texttt{Bench::Test::Remote}.

El constructor acepta los siguientes parámetros:

\begin{description}

\item[{\texttt{HOST:}}] \mbox{}

Máquina de destino sobre las que se lanzaran las
ejecuciones. Para un correcto funcionamiento se debe
tener acceso no interactivo mediante el mecanismo
clave publica-privada. 

\item[{\texttt{WORKDIR:}}] \mbox{}

Directorio de trabajo donde se encuentra 
el ejecutable y desde donde se llevarán a cabo todas las ejecuciones.

\item[{\texttt{EXECUTABLE:}}] \mbox{}

Nombre del fichero ejecutable.

\item[{\texttt{OUTPUTFILE:}}] \mbox{}

Parámetro opcional que indica el nombre del fichero
donde se encuentra la salida de la ejecucion del programa. Se 
utiliza cuando el programa vuelca la salida en un fichero
en lugar de mostrarla por pantalla.

\item[{\texttt{BASEDIR:}}] \mbox{}

Nombre del directorio donde se creará el fichero \texttt{.base}
generado como consecuencia de una llamada a \texttt{save\_result}.

\item[{\texttt{PREAMBLE} y \texttt{POSTAMBLE:}}] \mbox{}

Referencia a rutinas que serán llamadas justo después de
abrir y antes de cerrar la conexión con la máquina remota
respectivamente.

Ambas rutinas reciben como parámetro el objeto \texttt{GRID::Machine}
asociado a la máquina remota. Véase la documentación del módulo
\texttt{GRID::Machine} para conocer sus posibilidades.

\end{description}

\subsection{El método \texttt{get\_result}}

Véase una llamada típica:

\begin{verbatim}
   my $parameters = '-n 20 -p';
   my $output = $remote->get_result($parameters);
\end{verbatim}

El método \texttt{get\_result} acepta como único parámetro
una cadena de caracteres que contiene
los parámetros con los que se ejecutará el experimento
indicado en el constructor con el parámetro \texttt{EXECUTABLE} en
la máquina remota indicada con el parámetro \texttt{HOST}.

\subsection{El método \texttt{save\_result}}

Véase una llamada típica:

\begin{verbatim}
   $remote->save_result($parameters, $testname);
\end{verbatim}

El método \texttt{save\_result} acepta igual que \texttt{get\_result} una
cadena de caracteres con los parámetros de ejecución y el
nombre del test correspondiente.

El método \texttt{save\_result} automatiza la ejecución invocando
al método \texttt{get\_result} y guardando la salida en un fichero
de texto ubicado en el directorio definido en el constructor
con el parámetro \texttt{BASEDIR}. El nombre del archivo se
obtiene concatenando el parámetro \texttt{\$testname} con la
extensión \texttt{.base}.

\section{Véase también}

Para una mejor comprensión del módulo \texttt{Bench::Test::Remote},
véase también la documentación de los siguientes módulos:

\begin{itemize}
\item \texttt{Bench::Test}
\item \texttt{Bench::Test::Base}
\item \texttt{Bench::Test::Local}
\item \texttt{GRID::Machine}
\end{itemize}
